// 版权所有2011 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

/*
Package user allows user account lookups by name or id.

For most Unix systems, this package has two internal implementations of
resolving user and group ids to names, and listing supplementary group IDs.
One is written in pure Go and parses /etc/passwd and /etc/group. The other
is cgo-based and relies on the standard C library (libc) routines such as
getpwuid_r, getgrnam_r, and getgrouplist.

When cgo is available, and the required routines are implemented in libc
for a particular platform, cgo-based (libc-backed) code is used.
This can be overridden by using osusergo build tag, which enforces
the pure Go implementation.
*/
package user

import (
	"strconv"
)

// 对于特定平台，在init（）中这些可能被设置为false，和/或
// 构建标志，让测试知道跳过某些功能的测试。
var (
	userImplemented      = true
	groupImplemented     = true
	groupListImplemented = true
)

// 用户代表一个用户帐户。
type User struct {
	// Uid是用户ID。
	// 在POSIX系统上，这是代表Uid的十进制数。
	// 在Windows上，这是一个字符串格式的安全标识符（SID）。
	// 在计划9中，这是/dev/user的内容。
	Uid string
	// Gid是主要组ID。
	// 在POSIX系统上，这是代表Gid的十进制数。
	// 在Windows上，这是字符串格式的SID。
	// 在计划9中，这是/dev/user的内容。
	Gid string
	// 用户名是登录名。
	Username string
	// Name是用户的真实姓名或显示名。
	// 可能是空的。
	// 在POSIX系统上，这是GECOS字段
	// 列表中的第一个（或唯一一个）条目。
	// 在Windows上，这是用户的显示名。
	// 在计划9中，这是/dev/user的内容。
	Name string
	// HomeDir是指向用户主目录的路径（如果他们有）。
	HomeDir string
}

// 组表示一组用户。
// 
// 在POSIX系统上，Gid包含一个代表组ID的十进制数。
type Group struct {
	Gid  string // 组ID 
	Name string // 组名
}

// 当找不到用户时，LookupId将返回UnknownUserError。
type UnknownUserIdError int

func (e UnknownUserIdError) Error() string {
	return "user: unknown userid " + strconv.Itoa(int(e))
}

// 当找不到用户时，通过查找返回UnknownUserError。
type UnknownUserError string

func (e UnknownUserError) Error() string {
	return "user: unknown user " + string(e)
}

// 当找不到组时，LookupGroupId将返回UnknownGroupIdror。
type UnknownGroupIdError string

func (e UnknownGroupIdError) Error() string {
	return "group: unknown groupid " + string(e)
}

// 当找不到组时，LookupGroup返回UnknownGroupError。
type UnknownGroupError string

func (e UnknownGroupError) Error() string {
	return "group: unknown group " + string(e)
}
